/*
 * Copyright (c) 2011 Imre Fazekas.
 * All rights reserved.
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * Redistributions of source code must retain the above copyright notice, this
 * list of conditions and the following disclaimer.
 *
 * Redistributions in binary form must reproduce the above copyright notice,
 * this list of conditions and the following disclaimer in the documentation
 * and/or other materials provided with the distribution.
 * Neither the name of the Brillien nor the names of its
 * terms and concepts may be used to endorse or promote products derived from this
 * software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */

package com.vii.brillien.kernel.axiom;

import com.vii.brillien.kernel.BrillienException;
import com.vii.brillien.kernel.axiom.transport.Communication;

import java.util.Map;
import java.util.concurrent.Callable;

/**
 * Brillien represents the probelms of real world as a free communications' flow. Components have 3 roles basically: start, receive communication and alter during communications
 * This interface define all behaviors which belongs to actor part of its roles.
 * Every actor action should be defined in the execution thread dedicated to this component by the Liaison object
 */
public interface Aspirer<C extends Communication, R> extends Callable<R> {

    /**
     * After having all input parameters set, this method is called by the instantiation manager instance to make the Aspirer to activate itself
     */
    void                            plan() throws BrillienException;

    /**
     * Tells whether this Aspirer is waiting for input data to be activated. Will be automatically false after the execution of method setCallableInputData.
     */
    boolean                         isWaitingForInputData();

    /**
     * Activates the callable activity. Should be called once during the lifetime of the Aspirer object.
    */
    void                            activateCallable() throws BrillienException;

    /**
     * Passivates the callable activity. Can be called if the working Aspirer is required to stop.
    */
    void                            passivateCallable() throws BrillienException;

    /**
     * Tells whether this Presence has callable activity
     */
    boolean                         hasActivity();

    /**
     * Returns the result of the activity if it exists
     */
    R                               getResult();




    /**
     * Sends a get-like message to the given recipient. The method will not return until the response is arrived or a timeout event occured.
     * The parameters will be converted to Json format. In case of unsuccessful conversion, an exception will be thrown.
     * @param to name of the recipient
     * @param message message text
     * @param parameters parameters of the message
     * @return reponse message
     * @throws BrillienException
     */
    C           sendGet( String to, String message, Map<String, Object> parameters ) throws BrillienException;

    /**
     * Sends a get-like message to the given recipient. The method will not return until the response is arrived or a timeout event occured.
     * The parameters will be converted to Json format. In case of unsuccessful conversion, an exception will be thrown.
     * @param timeout timout of the waiting
     * @param to name of the recipient
     * @param message message text
     * @param parameters parameters of the message
     * @throws BrillienException
     */
    C           sendGet( long timeout, String to, String message, Map<String, Object> parameters ) throws BrillienException;

    /**
     * Sends a get-like message to the given recipient. The method will return immediately after having sent the message. The response will sent to this Aspirer through the given redirectMessage.
     * The parameters will be converted to Json format. In case of unsuccessful conversion, an exception will be thrown.
     * @param to name of the recipient
     * @param message message text
     * @param redirectMessage
     * @param parameters parameters of the message
     * @throws BrillienException
     */
    void        sendAGet( String to, String message, String redirectMessage, Map<String, Object> parameters ) throws BrillienException;

    /**
     * Sends a get-like message to the given recipient. The method will return immediately after having sent the message. The response will sent to this Aspirer through the given redirectMessage.
     * The parameters will be converted to Json format. In case of unsuccessful conversion, an exception will be thrown.
     * @param to name of the recipient
     * @param message message text
     * @param redirectEntityName name of the recivient who will be sent the message for
     * @param redirectMessage redirection message name
     * @param parameters parameters of the message
     * @throws BrillienException
     */
    void        sendDelegatedSet( String to, String message, String redirectEntityName, String redirectMessage, Map<String, Object> parameters ) throws BrillienException;

    /**
     * Sends a set-like message to the given recipient. The method will return immediately after having sent the message, no response is expected.
     * The parameters will be converted to Json format. In case of unsuccessful conversion, an exception will be thrown.
     * @param to name of the recipient
     * @param message message text
     * @param parameters parameters of the message
     * @throws BrillienException
     */
    void        sendSet( String to, String message, Map<String, Object> parameters ) throws BrillienException;

    /**
     * Sends a response to a previously received message.
     * The response will be converted to Json format. In case of unsuccessful conversion, an exception will be thrown.  
     * @param c previously received message
     * @param response response object
     * @throws BrillienException
     */
    void        sendResponse( C c, Object response ) throws BrillienException;

    /**
     * Sends an error message to a previously received message.
     * @param c previously received message
     * @param message error message
     * @throws BrillienException
     */
    void        sendError( C c, String message ) throws BrillienException;

    /**
     * Sends an error message to a previously received message.
     * @param c previously received message
     * @param message error message
     * @throws BrillienException
     */
    void        sendError( C c, int errorCode, String message ) throws BrillienException;

    /**
     * Sends an error message to a previously received message.
     * @param c previously received message
     * @param message error message
     * @throws BrillienException
     */
    void        sendError( C c, int errorCode, String message, Object value ) throws BrillienException;

    /**
     * Tells whether this Aspirer is waiting an answer to a redirected get-like message sent earlier.
     */
    boolean     isWaitingForResponse();








    /**
     * Sends a unit-wide get-like message to the given recipient. The method will not return until the response is arrived or a timeout event occured.
     * The parameters will be converted to Json format. In case of unsuccessful conversion, an exception will be thrown.
     * @param to name of the recipient
     * @param message message text
     * @param parameters parameters of the message
     * @return reponse messages
     * @throws BrillienException
     */
    C           sendUnitGet( String to, String message, Map<String, Object> parameters ) throws BrillienException;

    /**
     * Sends a unit-wide get-like message to the given recipient. The method will not return until the response is arrived or a timeout event occured.
     * The parameters will be converted to Json format. In case of unsuccessful conversion, an exception will be thrown.
     * @param timeout timout of the waiting
     * @param to name of the recipient
     * @param message message text
     * @param parameters parameters of the message
     * @return reponse messages
     * @throws BrillienException
     */
    C           sendUnitGet( int timeout, String to, String message, Map<String, Object> parameters ) throws BrillienException;

    /**
     * Sends a unit-wide get-like message to the given recipient. The method will return immediately after having sent the message. The response will sent to this Aspirer through the given redirectMessage.
     * The parameters will be converted to Json format. In case of unsuccessful conversion, an exception will be thrown.
     * @param to name of the recipient
     * @param message message text
     * @param redirectMessage
     * @param parameters parameters of the message
     * @throws BrillienException
     */
    void        sendUnitAGet( String to, String message, String redirectMessage, Map<String, Object> parameters ) throws BrillienException;

    /**
     * Sends a unit-wide get-like message to the given recipient. The method will return immediately after having sent the message. The response will sent to this Aspirer through the given redirectMessage.
     * The parameters will be converted to Json format. In case of unsuccessful conversion, an exception will be thrown.
     * @param to name of the recipient
     * @param message message text
     * @param redirectEntityName name of the recivient who will be sent the message for
     * @param redirectMessage redirection message name
     * @param parameters parameters of the message
     * @throws BrillienException
     */
    void        sendUnitDelegatedSet( String to, String message, String redirectEntityName, String redirectMessage, Map<String, Object> parameters ) throws BrillienException;

    /**
     * Sends a unit-wide set-like message to the given recipient. The method will return immediately after having sent the message, no response is expected.
     * The parameters will be converted to Json format. In case of unsuccessful conversion, an exception will be thrown.
     * @param to name of the recipient
     * @param message message text
     * @param parameters parameters of the message
     * @throws BrillienException
     */
    void        sendUnitSet( String to, String message, Map<String, Object> parameters ) throws BrillienException;

}
